package cn.iocoder.yudao.module.system.service.userretention;

import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.module.system.controller.admin.userretention.vo.UserRetentionPageReqVO;
import cn.iocoder.yudao.module.system.controller.admin.userretention.vo.UserRetentionRespVO;
import cn.iocoder.yudao.module.system.controller.admin.userretention.vo.UserRetentionStatsRespVO;
import cn.iocoder.yudao.module.system.dal.dataobject.userretention.UserRetentionStatsDO;

import java.time.LocalDate;
import java.util.List;

/**
 * 用户留存率计算服务接口
 *
 * @author 系统
 */
public interface UserRetentionService {

    /**
     * 计算用户留存率
     * 
     * @param targetDate 目标日期，计算该日期的留存率
     */
    void calculateRetentionRate(LocalDate targetDate);

    /**
     * 批量计算用户留存率
     * 
     * @param startDate 开始日期
     * @param endDate 结束日期
     */
    void batchCalculateRetentionRate(LocalDate startDate, LocalDate endDate);

    /**
     * 计算单个用户的留存率
     * 
     * @param userId 用户ID
     * @param usageDate 兑换码使用日期
     */
    void calculateUserRetentionRate(Long userId, LocalDate usageDate);

    /**
     * 获取用户留存率统计分页
     * 
     * @param pageReqVO 分页查询条件
     * @return 分页结果
     */
    PageResult<UserRetentionRespVO> getUserRetentionPage(UserRetentionPageReqVO pageReqVO);

    /**
     * 获取留存率统计概览
     * 
     * @return 统计概览
     */
    UserRetentionStatsRespVO getUserRetentionStats();

    /**
     * 获取用户留存率详情
     * 
     * @param id 记录ID
     * @return 用户留存率详情
     */
    UserRetentionRespVO getUserRetention(Long id);

    /**
     * 计算用户留存率
     * 
     * @param userId 用户ID
     */
    void calculateUserRetention(Long userId);

    /**
     * 批量计算用户留存率
     * 
     * @param userIds 用户ID列表
     */
    void calculateUserRetentionBatch(List<Long> userIds);

    /**
     * 重新计算留存率
     * 
     * @param startDate 开始日期
     * @param endDate 结束日期
     */
    void recalculateRetention(LocalDate startDate, LocalDate endDate);

    /**
     * 删除过期数据
     * 
     * @param beforeDate 删除此日期之前的数据
     * @return 删除的记录数
     */
    int deleteExpiredData(LocalDate beforeDate);

    /**
     * 获取计算进度
     * 
     * @return 计算进度百分比
     */
    double getCalculationProgress();

    /**
     * 获取用户留存率详情
     * 
     * @param userId 用户ID
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 用户留存率详情列表
     */
    List<UserRetentionStatsDO> getUserRetentionDetails(Long userId, LocalDate startDate, LocalDate endDate);

    /**
     * 删除过期的留存率统计数据
     * 
     * @param beforeDate 删除此日期之前的数据
     * @return 删除的记录数
     */
    int deleteExpiredRetentionStats(LocalDate beforeDate);

    /**
     * 重新计算用户留存率
     * 
     * @param userId 用户ID
     * @param usageLogId 使用记录ID
     */
    void recalculateUserRetentionRate(Long userId, Long usageLogId);

    /**
     * 获取待计算留存率的记录数量
     * 
     * @return 待计算记录数量
     */
    long getPendingCalculationCount();

    /**
     * 获取留存率计算进度
     * 
     * @param targetDate 目标日期
     * @return 计算进度百分比
     */
    double getCalculationProgress(LocalDate targetDate);
}